home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 85 / CD Actual 85 Febrero 2004.iso / Experto / Apache / apache_2.0.48-win32-x86-no_ssl.msi / Data.Cab / F251772_apr_strings.h < prev    next >
Encoding:
C/C++ Source or Header  |  2003-03-05  |  14.4 KB  |  374 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2003 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. /* Portions of this file are covered by */
  56. /* -*- mode: c; c-file-style: "k&r" -*-
  57.  
  58.   strnatcmp.c -- Perform 'natural order' comparisons of strings in C.
  59.   Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
  60.  
  61.   This software is provided 'as-is', without any express or implied
  62.   warranty.  In no event will the authors be held liable for any damages
  63.   arising from the use of this software.
  64.  
  65.   Permission is granted to anyone to use this software for any purpose,
  66.   including commercial applications, and to alter it and redistribute it
  67.   freely, subject to the following restrictions:
  68.  
  69.   1. The origin of this software must not be misrepresented; you must not
  70.      claim that you wrote the original software. If you use this software
  71.      in a product, an acknowledgment in the product documentation would be
  72.      appreciated but is not required.
  73.   2. Altered source versions must be plainly marked as such, and must not be
  74.      misrepresented as being the original software.
  75.   3. This notice may not be removed or altered from any source distribution.
  76. */
  77.  
  78. #ifndef APR_STRINGS_H
  79. #define APR_STRINGS_H
  80.  
  81. /**
  82.  * @file apr_strings.h
  83.  * @brief APR Strings library
  84.  */
  85.  
  86. #include "apr.h"
  87. #include "apr_errno.h"
  88. #include "apr_pools.h"
  89. #define APR_WANT_IOVEC
  90. #include "apr_want.h"
  91.  
  92. #if APR_HAVE_STDARG_H
  93. #include <stdarg.h>
  94. #endif
  95.  
  96. #ifdef __cplusplus
  97. extern "C" {
  98. #endif /* __cplusplus */
  99.  
  100. /**
  101.  * @defgroup apr_strings String routines
  102.  * @ingroup APR 
  103.  * @{
  104.  */
  105.  
  106. /**
  107.  * Do a natural order comparison of two strings.
  108.  * @param a The first string to compare
  109.  * @param b The second string to compare
  110.  * @return Either <0, 0, or >0.  If the first string is less than the second
  111.  *          this returns <0, if they are equivalent it returns 0, and if the
  112.  *          first string is greater than second string it retuns >0.
  113.  */
  114. APR_DECLARE(int) apr_strnatcmp(char const *a, char const *b);
  115.  
  116. /**
  117.  * Do a natural order comparison of two strings ignoring the case of the 
  118.  * strings.
  119.  * @param a The first string to compare
  120.  * @param b The second string to compare
  121.  * @return Either <0, 0, or >0.  If the first string is less than the second
  122.  *         this returns <0, if they are equivalent it returns 0, and if the
  123.  *         first string is greater than second string it retuns >0.
  124.  */
  125. APR_DECLARE(int) apr_strnatcasecmp(char const *a, char const *b);
  126.  
  127. /**
  128.  * duplicate a string into memory allocated out of a pool
  129.  * @param p The pool to allocate out of
  130.  * @param s The string to duplicate
  131.  * @return The new string
  132.  */
  133. APR_DECLARE(char *) apr_pstrdup(apr_pool_t *p, const char *s);
  134.  
  135. /**
  136.  * Create a null-terminated string by making a copy of a sequence
  137.  * of characters and appending a null byte
  138.  * @param p The pool to allocate out of
  139.  * @param s The block of characters to duplicate
  140.  * @param n The number of characters to duplicate
  141.  * @return The new string
  142.  * @remark This is a faster alternative to apr_pstrndup, for use
  143.  *         when you know that the string being duplicated really
  144.  *         has 'n' or more characters.  If the string might contain
  145.  *         fewer characters, use apr_pstrndup.
  146.  */
  147. APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n);
  148.  
  149. /**
  150.  * duplicate the first n characters of a string into memory allocated 
  151.  * out of a pool; the new string will be null-terminated
  152.  * @param p The pool to allocate out of
  153.  * @param s The string to duplicate
  154.  * @param n The number of characters to duplicate
  155.  * @return The new string
  156.  */
  157. APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n);
  158.  
  159. /**
  160.  * Duplicate a block of memory.
  161.  *
  162.  * @param p The pool to allocate from
  163.  * @param m The memory to duplicate
  164.  * @param n The number of bytes to duplicate
  165.  * @return The new block of memory
  166.  */
  167. APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n);
  168.  
  169. /**
  170.  * Concatenate multiple strings, allocating memory out a pool
  171.  * @param p The pool to allocate out of
  172.  * @param ... The strings to concatenate.  The final string must be NULL
  173.  * @return The new string
  174.  */
  175. APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...);
  176.  
  177. /**
  178.  * Concatenate multiple strings specified in a writev-style vector
  179.  * @param p The pool from which to allocate
  180.  * @param vec The strings to concatenate
  181.  * @param nvec The number of strings to concatenate
  182.  * @param nbytes (output) strlen of new string (pass in NULL to omit)
  183.  * @return The new string
  184.  */
  185. APR_DECLARE(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec,
  186.                                  apr_size_t nvec, apr_size_t *nbytes);
  187.  
  188. /**
  189.  * printf-style style printing routine.  The data is output to a string 
  190.  * allocated from a pool
  191.  * @param p The pool to allocate out of
  192.  * @param fmt The format of the string
  193.  * @param ap The arguments to use while printing the data
  194.  * @return The new string
  195.  */
  196. APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap);
  197.  
  198. /**
  199.  * printf-style style printing routine.  The data is output to a string 
  200.  * allocated from a pool
  201.  * @param p The pool to allocate out of
  202.  * @param fmt The format of the string
  203.  * @param ... The arguments to use while printing the data
  204.  * @return The new string
  205.  */
  206. APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...)
  207.         __attribute__((format(printf,2,3)));
  208.  
  209. /**
  210.  * copy n characters from src to dst
  211.  * @param dst The destination string
  212.  * @param src The source string
  213.  * @param dst_size The space available in dst; dst always receives
  214.  *                 null-termination, so if src is longer than
  215.  *                 dst_size, the actual number of characters copied is
  216.  *                 dst_size - 1.
  217.  * @remark
  218.  * <PRE>
  219.  * We re-implement this function to implement these specific changes:
  220.  *       1) strncpy() doesn't always null terminate and we want it to.
  221.  *       2) strncpy() null fills, which is bogus, esp. when copy 8byte strings
  222.  *          into 8k blocks.
  223.  *       3) Instead of returning the pointer to the beginning of the
  224.  *          destination string, we return a pointer to the terminating null
  225.  *          to allow us to check for truncation.
  226.  * </PRE>
  227.  */
  228. APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src,
  229.                                 apr_size_t dst_size);
  230.  
  231. /**
  232.  * Strip spaces from a string
  233.  * @param dest The destination string.  It is okay to modify the string
  234.  *             in place.  Namely dest == src
  235.  * @param src The string to rid the spaces from.
  236.  */
  237. APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src);
  238.  
  239. /**
  240.  * Convert the arguments to a program from one string to an array of 
  241.  * strings terminated by a NULL pointer
  242.  * @param arg_str The arguments to convert
  243.  * @param argv_out Output location.  This is a pointer to an array of strings.
  244.  * @param token_context Pool to use.
  245.  */
  246. APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str,
  247.                                                char ***argv_out,
  248.                                                apr_pool_t *token_context);
  249.  
  250. /**
  251.  * Split a string into separate null-terminated tokens.  The tokens are 
  252.  * delimited in the string by one or more characters from the sep
  253.  * argument.
  254.  * @param str The string to separate; this should be specified on the
  255.  *            first call to apr_strtok() for a given string, and NULL
  256.  *            on subsequent calls.
  257.  * @param sep The set of delimiters
  258.  * @param last Internal state saved by apr_strtok() between calls.
  259.  * @return The next token from the string
  260.  */
  261. APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last);
  262.  
  263. /**
  264.  * @defgroup APR_Strings_Snprintf snprintf implementations
  265.  * @warning
  266.  * These are snprintf implementations based on apr_vformatter().
  267.  *
  268.  * Note that various standards and implementations disagree on the return
  269.  * value of snprintf, and side-effects due to %n in the formatting string.
  270.  * apr_snprintf (and apr_vsnprintf) behaves as follows:
  271.  *
  272.  * Process the format string until the entire string is exhausted, or
  273.  * the buffer fills.  If the buffer fills then stop processing immediately
  274.  * (so no further %n arguments are processed), and return the buffer
  275.  * length.  In all cases the buffer is NUL terminated. It will return the
  276.  * number of characters inserted into the buffer, not including the
  277.  * terminating NUL. As a special case, if len is 0, apr_snprintf will
  278.  * return the number of characters that would have been inserted if
  279.  * the buffer had been infinite (in this case, *buffer can be NULL)
  280.  *
  281.  * In no event does apr_snprintf return a negative number.
  282.  * @{
  283.  */
  284.  
  285. /**
  286.  * snprintf routine based on apr_vformatter.  This means it understands the
  287.  * same extensions.
  288.  * @param buf The buffer to write to
  289.  * @param len The size of the buffer
  290.  * @param format The format string
  291.  * @param ... The arguments to use to fill out the format string.
  292.  */
  293. APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len,
  294.                                      const char *format, ...)
  295.         __attribute__((format(printf,3,4)));
  296.  
  297. /**
  298.  * vsnprintf routine based on apr_vformatter.  This means it understands the
  299.  * same extensions.
  300.  * @param buf The buffer to write to
  301.  * @param len The size of the buffer
  302.  * @param format The format string
  303.  * @param ap The arguments to use to fill out the format string.
  304.  */
  305. APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format,
  306.                                va_list ap);
  307. /** @} */
  308.  
  309. /**
  310.  * create a string representation of an int, allocated from a pool
  311.  * @param p The pool from which to allocate
  312.  * @param n The number to format
  313.  * @return The string representation of the number
  314.  */
  315. APR_DECLARE(char *) apr_itoa(apr_pool_t *p, int n);
  316.  
  317. /**
  318.  * create a string representation of a long, allocated from a pool
  319.  * @param p The pool from which to allocate
  320.  * @param n The number to format
  321.  * @return The string representation of the number
  322.  */
  323. APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n);
  324.  
  325. /**
  326.  * create a string representation of an apr_off_t, allocated from a pool
  327.  * @param p The pool from which to allocate
  328.  * @param n The number to format
  329.  * @return The string representation of the number
  330.  */
  331. APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n);
  332.  
  333. /**
  334.  * parse a numeric string into a 64-bit numeric value
  335.  * @param buf The string to parse. It may contain optional whitespace,
  336.  *   followed by an optional '+' (positive, default) or '-' (negative)
  337.  *   character, followed by an optional '0x' prefix if base is 0 or 16,
  338.  *   followed by numeric digits appropriate for base.
  339.  * @param end A pointer to the end of the valid character in buf. If
  340.  *   not nil, it is set to the first invalid character in buf.
  341.  * @param base A numeric base in the range between 2 and 36 inclusive,
  342.  *   or 0.  If base is zero, buf will be treated as base ten unless its
  343.  *   digits are prefixed with '0x', in which case it will be treated as
  344.  *   base 16.
  345.  * @return The numeric value of the string.
  346.  */
  347. APR_DECLARE(apr_int64_t) apr_strtoi64(const char *buf, char **end, int base);
  348.  
  349. /**
  350.  * parse a base-10 numeric string into a 64-bit numeric value.
  351.  * Equivalent to apr_strtoi64(buf, (char**)NULL, 10).
  352.  * @param buf The string to parse
  353.  * @return The numeric value of the string
  354.  */
  355. APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf);
  356.  
  357. /**
  358.  * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t,
  359.  * as bytes, K, M, T, etc, to a four character compacted human readable string.
  360.  * @param size The size to format
  361.  * @param buf The 5 byte text buffer (counting the trailing null)
  362.  * @return The buf passed to apr_strfsize()
  363.  * @remark All negative sizes report '  - ', apr_strfsize only formats positive values.
  364.  */
  365. APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf);
  366.  
  367. /** @} */
  368.  
  369. #ifdef __cplusplus
  370. }
  371. #endif
  372.  
  373. #endif  /* !APR_STRINGS_H */
  374.